Providing Two-Factor Authentication for CygNet Bridge API

Provide two-factor authentication to add an additional layer of security when using CygNet Bridge API over the web. When the option is available, providing two-factor authentication (2FA) better protects access to your CygNet data and controls. To provide two-factor authentication, you must set it up for applicable parts of your system. Currently two-factor authentication can be used with the CygNet Bridge API feature in CygNet Bridge.

Configuring the Two-Factor Authentication Mode

Configure the settings governing usage of two-factor authentication during installation of CygNet Bridge API, in the Multi-factor authentication section of the CygNet Bridge installer. The Two-factor mode selection determines how, or if, two-factor authentication is available for use with CygNet Bridge API. Possible settings are as follows.

• Disabled - CygNet Bridge API has not enabled the use of 2FA; this is the default setting
• Optional - each CygNet Bridge API user can decide whether or not they want to use 2FA
• Required - all CygNet Bridge API users are required to use 2FA

See Installing CygNet Bridge for more information about selecting 2FA mode during the installation process.

Providing Two-Factor Authentication

Providing two-factor authentication for CygNet Bridge API adds considerations to your preparation process. If you intend on using two-factor authentication, plan your CygNet Bridge installation to include the following elements.

Use the following procedure to provide two-factor authentication for CygNet Bridge API.

To Provide Two-Factor Authentication for CygNet Bridge API

1. Complete the following preparations for two-factor authentication.

1. Verify or create a dedicated Group service (GRP service type) in your CygNet installation, to use specifically for storing user authentication information. See Preparing your System for CygNet Bridge API for more information about the process.

   Note: During CygNet Bridge and Bridge API installation, when 2FA is enabled, the new Group service information will be required in the "Multi-factor authentication" section of the Bridge API page.

2. Secure access to a mobile phone device capable of installing and running a two-factor authenticator app and scanning a QR code as necessary.
3. Select an authenticator app capable of generating a time-based, one-time passcode, that meets your needs and is compatible with your mobile phone device. Install the authenticator app you have selected on your mobile phone device.
4. Install CygNet Bridge, with the CygNet Bridge API feature selected, the multi-factor authentication mode set to Optional or Required, and information supplied for the dedicated Group service. See Installing CygNet Bridge for more information.
5. Start your CygNet Bridge site in the IIS Manager.

Enabling Two-Factor Authentication for a User Account

When the multi-factor authentication mode is set to Required, all users must enable 2FA for their user login. When the mode is set to Optional, each user can decide whether or not to enable 2FA.

To Enable Two-Factor Authentication for Your User Account

Using your API client, do the following to enable two-factor authentication for your user account.

1. Access the QR code and generate an authentication passcode.

1. Create a GET clientloginapi/api/login/tfa-qr request to generate the CygNet Bridge API QR code image data.
2. Provide your user credentials (user name, password, and domain/workstation etc. if applicable).
3. Display the QR code image data contained in the response.
4. Using the 2FA app on your mobile phone device, scan the QR code and process the image to produce an authentication passcode.

   Note: You can still change your mind and stop the setup process at this point, if desired. The passcode will not become required until the next step (confirmation) is complete.

2. Confirm the authentication passcode.

1. Create a GET clientloginapi/api/login/tfa-confirm request to confirm the authentication passcode.
2. Provide your user credentials (user name, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Enter the authentication passcode generated by your 2FA app into the value column of the X-WFT-AuthCode header.

   Note: Once the confirmation action is complete, the X-WFT-AuthCode header will be required to log in successfully, until it is reset by an administrator.

3. Optionally log in at this time, to verify the process and generate an authentication token.

1. Create a GET clientloginapi/api/login request to log in using the authentication passcode.
2. Provide your user credentials (user name, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Provide the authentication passcode generated by your 2FA app into the value column of the X-WFT-AuthCode header.

   Note: Because the authentication passcode is time based, you may need to regenerate the code using your 2FA app. Repeat as necessary.

5. The authentication token contained in the response is used in your CygNet Bridge API calls.

Using Two-Factor Authentication for CygNet Bridge API

Once it is set up, your CygNet Bridge API calls will have the additional protections of two-factor authentication. In Required multi-factor authentication mode, all users must use 2FA. In Optional mode, users may use 2FA if they choose.

When you access the CygNet Bridge API, do the following to use two-factor authentication.

1. Using your API client, log in to CygNet Bridge API using your authorization credentials and 2FA passcode.

1. Create a GET clientloginapi/api/login request.
2. Provide your user credentials (user name, password, and domain/workstation etc. if applicable).
3. Add a header named X-WFT-AuthCode.
4. Provide the authentication passcode generated by your 2FA app in the X-WFT-AuthCode header.

   Note: Because the authentication passcode is time based, you may need to regenerate the code using your 2FA app. Repeat as necessary.

5. The authentication token contained in the response is used by your CygNet Bridge API calls.

2. Create a CygNet Bridge API request including the authentication token.

1. Create a CygNet Bridge API request.
2. Add a header named X-WFT-AuthToken.
3. Provide the authentication token generated at login in the X-WFT-AuthToken header.

More:

Managing Two-Factor Authentication Users